Wi-Fi hotspot authentication sample

This sample demonstrates how to use the Hotspot Authentication API (Windows.Networking.NetworkOperators) on both Windows and Windows Phone clients.

Note  This sample was created using one of the universal app templates available in Visual Studio. It shows how its solution is structured so it can run on both Windows 8.1 and Windows Phone 8.1. For more info about how to build apps that target Windows and Windows Phone with Visual Studio, see Build apps that target Windows and Windows Phone 8.1 by using Visual Studio.

The sample consists of four projects: Windows Phone, Windows, Shared, and a background task (HotspotAuthenticationTask). The code in the shared and background task is common to both platforms.

Even though a large part of the Hotspot Authentication API is converged and the code is shared between the Windows and Windows Phone projects, we want you to be aware of these key differences:

• Wireless Internet Service Provider roaming (WISPr) requirement for access points:

  • Windows To invoke the hotspot authentication flow (background task), the access point being connected to must provide a captive portal response with WISPr support claimed in the XML blob being returned to the client.

  • Windows Phone There is no requirement for captive portal or WISPr support on the access point. In this case, the background task is launched as soon as the Wi-Fi connection to the access point is completed and an IP address is acquired regardless of whether the access point claims WISPr support or not.

• Authentication using WISPr:

  • Windows The Hotspot Authentication API supports two ways of completing authentication:

    • Issuing WISPr credentials by using the HotspotAuthenticationContext.IssueCredentialsAsync method, which uses the native WISPr implementation of Windows.
    • Performing a custom WISPr authentication by using the info obtained through the HotspotAuthenticationContext.TryGetAuthenticationContext method. In this case, you must call the HotspotAuthenticationContext.SkipAuthentication method to skip the Native WISPr authentication process after the custom authentication is complete.

  • Windows Phone There is no native WISPr support. As a result, the HotspotAuthenticationContext.IssueCredentialsAsync method isn't supported (throws NotImplementedException). The only way to perform WISPr authentication on the Windows Phone platform is to implement it within the app and then call the HotspotAuthenticationContext.SkipAuthentication method.

• Contents of HotspotAuthenticationContext class:

  • Windows All of the properties of a HotspotAuthenticationContext object are valid.

  • Windows Phone The only valid properties of a HotspotAuthenticationContext object are HotspotAuthenticationContext.WirelessNetworkId (SSID) and HotspotAuthenticationContext.NetworkAdapter. This is because the remaining properties are obtained from the native WISPr implementation of Windows, which isn't supported on Windows Phone.

If your supported list of access points are all WISPr-based and your app implements WISPr authentication itself, your app's solution will result in 100% sharing of Hotspot Authentication API code between Windows Phone and Windows.

To obtain an evaluation copy of Windows 8.1, go to Windows 8.1.

To obtain an evaluation copy of Microsoft Visual Studio 2013 Update 2, go to Microsoft Visual Studio 2013.

Related topics

Mobile Broadband on the Windows Hardware Dev Center

HotspotAuthenticationContext

HotspotAuthenticationEventDetails

IBackgroundTask

IBackgroundTaskInstance

Windows 8 app samples

Related technologies

Operating system requirements

Build the sample

1. Start Visual Studio 2013 Update 2 and select File > Open > Project/Solution.
2. Go to the directory to which you unzipped the sample. Then go to the subdirectory containing the sample in the language you desire - either C++, C#, or JavaScript. Double-click the Visual Studio 2013 Update 2 Solution (.sln) file.
3. Select either the Windows or Windows Phone project version of the sample and either the app or task version. Press Ctrl+Shift+B, or select Build > Build Solution.

Run the sample

The Wi-Fi hotspot authentication sample has two requirements to run:

• Windows must be provisioned to trigger the application when authenticating with a certain hotspot. This is achieved by provisioning a WLAN profile with a corresponding configuration. The provisioning XML must either be signed to be consumed by the provisioning API, or this sample must be part of a privileged mobile network operator companion application.
• The provisioning XML built into this application must be modified to match the hotspot's SSID and signed before it can be applied.

The steps for completing these requirements and running the sample are described below:

1. Modify the Provisioning Metadata XML file to match your hotspot by opening ProvisioningData.xml and adjusting the following fields:
   1. CarrierProvisioning\Global\CarrierID:
      • If writing a mobile broadband operator app, use the same GUID that you specified as the Service Number in the metadata authoring wizard.
      • If writing a hotspot-only app, generate a new GUID with Visual Studio. On the Tools menu, click Create GUID. Click Copy to transfer the new GUID to the Clipboard.
   2. CarrierProvisioning\Global\SubscriberID:
      • If writing a mobile broadband operator app, use the International Mobile Subscriber Identity (IMSI) of the mobile broadband SIM.
      • If writing a hotspot-only app, use any unique identifier appropriate to your service, such as a username or account number.
   3. CarrierProvisioning\WLANProfiles\WLANProfile\name: Name of your service or test Access Point (AP).
   4. CarrierProvisioning\WLANProfiles\WLANProfile\SSIDConfig\SSID\name: Configured SSID of your test hotspot.
   5. CarrierProvisioning\WLANProfiles\WLANProfile\MSM\security\HotspotProfile\ExtAuth\ExtensionId: Package family name of the application. To retrieve this name:
      • In Visual Studio, open package.appmanifest
      • Click on the Packaging tab
      • Copy the Package Family Name
2. Authenticate access to the Provisioning Agent APIs
   • Hotspot-only operators: Sign the modified Provisioning Metadata XML file
     1. Open a PowerShell console
     2. Type the following command to import the Provisioning tools:

        Import-Module "<path_to_Win8_sdk>\bin\<arch>\ProvisioningTestHelper.psd1"

     3. Create and install a test Extended Validation certificate:

        Install-TestEVCert -CertName <Certificate Name>

     4. Use the new certificate to sign the provisioning file:

        ConvertTo-SignedXml -InputFile <complete path to the input XML file> -OutputFile <complete path to the output XML file> -CertName <name of the certificate used to sign the xml>

     5. Replace ProvisioningData.xml with the signed file.
   • Mobile broadband operators: Modify the sample to use an unsigned Provisioning Metadata XML file
     1. Open HotspotAuthenticationApp\Initialization.xaml.cs (or Initialization.xaml.cpp, or js\initialization.js) in Visual Studio
     2. Locate the call to the ProvisioningAgent constructor:

        // Create ProvisiongAgent Object 
        var provisioningAgent = new ProvisioningAgent();
        

     3. Replace this with a call to the privileged ProvisioningAgent interface:

        // Create ProvisiongAgent Object 
        var accountIds = Windows.Networking.NetworkOperators.MobileBroadbandAccount.AvailableNetworkAccountIds;
        
        if( accountIds.Count == 0 ) {
          // Throw Exception here; metadata not correctly installed
        }
        
        // For simplicity, using the first account ID.
        var provisioningAgent = Windows.Networking.NetworkOperators.ProvisioningAgent.CreateFromNetworkAccountId(accountIds[0]); 
        

3. Provide appropriate credentials for your test AP
   • If the test AP uses fixed credentials: Modify HotspotAuthenticationTask\ConfigStore.cs to return a valid username and password for your test AP.
   • If the test AP uses dynamic credentials: In HotspotAuthenticationTask\BackgroundTask.cs, replace the reference to ConfigStore with your own business logic to generate/retrieve appropriate credentials for the network.

Run this sample after completing the preceding steps.

The next steps depend on whether you just want to deploy the sample or you want to both deploy and run it.

Deploying the sample

1. Select either the Windows or Windows Phone project version of the sample and either the app or task version.
2. Select Build > Deploy Solution.

Deploying and running the sample

1. Right-click either the Windows or Windows Phone project version and either the app or task version of the sample in Solution Explorer and select Set as StartUp Project.
2. To debug the sample and then run it, press F5 or select Debug > Start Debugging. To run the sample without debugging, press Ctrl+F5 or selectDebug > Start Without Debugging.